home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1995 October
/
EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso
/
Aminet
/
comm
/
misc
/
DevHandler103.lha
/
DevHandler.doc
< prev
next >
Wrap
Text File
|
1995-05-08
|
18KB
|
481 lines
The DEV Handler 1.03
Console, AUX and Raw Disk Handler
(c) 1995 Martin Mares, MJSoft System Software
================================================================================
Preface
=======
The DEV Handler package and its documentation are Copyright (c) Martin Mares,
MJSoft System Software, Prague, Czech Republic.
This archive can be freely redistributed as long as all of its files are
included in their original form without any additions, deletions or
modifications (excluding addition of other README-style files and icons) and no
more than a nominal fee is charged for its distribution. All copyright notices
in the programs and accompanying documentation files must remain intact. It's
especially forbidden to add various '.displayme' files and BBS advertisements.
This style of distribution is generally known as FREEWARE.
Special permission is given to Fred Fish to include this software on his
"Fish Disks".
This software is provided "AS IS" without warranty of any kind, either
expressed or implied. The author is not responsible for any damage caused by
it.
Introduction
============
- UNIX has named consoles. Amiga doesn't. They're very useful when you need
to say which console is someone logged on (a good example are the who and write
utilities).
- UNIX has special files representing devices. Amiga doesn't. They're very
useful for tar-like programs to access the devices directly without knowing
about Amiga device concept (by the way, the Amiga access is much more better
than the one in UNIX, because it's completely asynchronous, but sometimes you
prefer simplicity even with lower efficiency).
- UNIX consoles and special files have multiuser protection. Amiga doesn't.
- There was no console and AUX handler satisfying all my requirements.
This handler tries to be a solution to all of these problems. It creates a
disk-like volume named Devices containing devices of the following kinds:
(1) Consoles. Each console can have its own screen. Also borderless windows
and similar specialities are supported. You can open the screen and set
its parameters (including colors) without using any other tool. The
keyboard command set is slightly extended. All standard packets are
supported.
(2) AUX devices. Something like console, but connected to a serial-like
device instead of a window. When the carrier is lost, EOF is sent to
all pending read requests and a break signal is sent to processes which
use the console.
(3) Softlinks. You can install a soft link to any file. Icons may be
handled this way. You can also make all your volumes to DEV:
(4) Raw access to devices. Both stream and block devices are supported.
Installation and configuration
==============================
Copy DEVHandler to your handler directory (usually L:) and create a mount
entry for it (in DEVS:Mountlist or DEVS:DOSDrivers/DEV, according to system
version you use):
DEV: Handler = L:DEVHandler /* Correct this path */
StackSize = 2048
Priority = 5
GlobVec = -1
Startup = S:DEVHandler.config /* Or any name you want */
Also copy the Force command somewhere you like to have it in.
After these steps, it would be good to create the configuration file
mentioned in the mount entry. This file is a normal text file with comments
introduced by semicolons (everything from the first semicolon to the end of the
line is ignored). It consists of definition blocks - one for each device.
Possible parameters are listed here: (many of them may be omitted, the
required ones are marked with [R])
(1) Screen definition:
SCREEN <name> [R] Name of public screen (must be the first line)
WIDTH <n> Screen width in pixels (default=as Workbench)
HEIGHT <n> Screen height in pixels (default=as Workbench)
DEPTH <n> Number of bitplanes (default=as Workbench)
TITLE <title> Screen title
DISPLAYID <mode> Display mode for this screen = MonitorType
(0=default, $21000=PAL, $11000=NTSC, $31000=VGA,
$41000=A2024, $61000=EURO72, $71000=EURO36,
$81000=SUPER72, $91000=DBLNTSC, $A1000=DBLPAL)
+ $8000 for HIRES / $8020 for SUPERHIRES
+ $0004 for interlace
+ $0080 for halfbrite mode
(for other idents see graphics/modeid.[ih])
BEHIND <b> If active (set to 1), the screen is opened in
behind the others.
AUTOSCROLL <b> If active, the screen is autoscrolled if it's
larger than the visible display.
COLOR0 <n> RGB value for color #0 ($000 to $FFF)
COLOR1 <n> RGB value for color #1 ($000 to $FFF)
COLOR2 <n> RGB value for color #2 ($000 to $FFF)
COLOR3 <n> RGB value for color #3 ($000 to $FFF)
(2) Console definition:
CONSOLE <name> [R] Name of console device (must be the first line)
LEFT <n> Left edge of the window (default=0)
TOP <n> Top edge of the window (default=0)
WIDTH <n> Width of the window (default=full screen)
HEIGHT <n> Height of the window (default=full screen)
TITLE <s> Window title (don't set for backdrop windows)
ACTIVE <b> If active, the window is activated when opened
BORDERLESS <b> If active, the window has no border
PUBSCREEN <name> Open the window on the specified public screen
CLIP <b> If active, console clipping is allowed
BUFSIZE <n> Size of input buffer (default=512 bytes)
UNIXMODE <b> If active, it behaves as on UNIX systems - if
you type anything, the output is not suppressed.
The only way to stop it is using of CTRL-S
(XOFF), continue by CTRL-Q (XON).
HISTSIZE <n> Size of history buffer (default=1024 bytes).
If zero, no history is available.
RMBTRAP <b> If active, the right mouse button is ignored
and doesn't stop console output.
(3) AUX definition:
AUX <name> [R] Name of AUX device (must be the first line)
DEVICE <name> [R] Name of device to be used for I/O
UNIT <n> Device unit to be used (default=0)
FLAGS <n> Device flags to be used (default=0)
BUFLEN <n> Device buffer size (default set by the device)
BAUD <n> Baud rate (default=9600)
BITS <n> Number of data bits (default=8)
STOPBITS <n> Number of stop bits (default=1)
SERFLAGS <n> Flags for the serial device:
$00=no parity, $01=even, $03=odd
+ $04 for RS-232 7-wire protocol
+ $10 for high-speed mode
+ $20 for shared access
+ $80 for XON/XOFF mode (default=$20)
CHECKCD <n> Carrier will be tested. In case it's been lost,
all read requests are returned with EOF, all
writes are rejected with write error and breaks
are sent to all users. (default=0)
TERM <n> Terminal type: 0=Amiga, 1=Amiga with CR+LF,
2=something which should work with VT100
(default=0)
BUFSIZE <n> Size of input buffer (default=512 bytes)
UNIXMODE <b> If active, it behaves as on UNIX systems - if
you type anything, the output is not suppressed.
The only way to stop it is using of CTRL-S
(XOFF), continue by CTRL-Q (XON).
HISTSIZE <n> Size of history buffer (default=1024 bytes).
If zero, no history is available.
(4) Softlink definition:
LINK <name> [R] Name of the link (must be the first line)
DEST <s> [R] Link destination
(5) Raw device definition:
RAWDEVICE <name> [R] Name of the device (must be the first line)
DEVICE <s> [R] System device to be used
UNIT <n> Device unit (default=0)
FLAGS <n> Device flags (default=0)
BUFMEMTYPE <n> Memory type for I/O buffers (1=any, 3=chip,
5=fast ; default=1)
BLOCKSIZE <n> Size of one block (not specified or zero for
stream devices)
BUFFER <n> Buffer size in blocks (or bytes if stream dev)
Stream devices have buffered only writes (or
nothing if no buffer is specified). Block
devices must have some buffer.
SIZE <n> Device size in bytes (0=stream, -1=infinite,
-2=autodetect via ReadGeometry command)
EXCLUSIVE <b> If active, only one open at a time is allowed
UPDATE <b> If active, the UPDATE command is sent after last
write request. Use for trackdisk-like devices.
MOTOR <b> If active, turn off drive motor after the device
is closed. Use for trackdisk-like devices.
CLEAR <b> If active, all device buffers are flushed (via
the CLEAR command) when a read/write error is
detected.
READCMD <n> Device command number used for reading.
(default=2=CMD_READ)
WRITECMD <n> Device command number used for writing.
(default=3=CMD_WRITE)
(6) Global parameters (can be used for any device)
PERMANENT <b> If active, the device is always in opened state.
If not set, the device is activated when it's
opened and deactivated when closed. (If you
specify a permanent screen, it will be still
open. If it is not permanent (default), it will
be opened as soon as some console will try to
use it.)
FROM <name> Copy all settings from given device defined
before this one. The device must be of the same
type as the current one.
Warning #1: Strings are not enclosed in quotes, even if they contain spaces.
Warning #2: DEVHandler is not foolproof. If you specify incorrect values of
some options, it might crash.
If a fatal error in the config file is found, a small window is opened and
the error is announced. After this, the handler exits normally.
For some examples, see the example config file (DevHandler.config) in this
archive.
Differences
===========
There are some differences between DEVHandler consoles and the standard CBM
CON handler:
- Large writes are split automatically allowing to stop any write between
lines.
- Control sequences are buffered, so if you send a control sequence in two
consecutive writes, the console won't insert anything between them (in
standard CON, you can type a character inside it!).
- If you use the RCOMMAND-V (paste) combination in raw mode, the control
sequence for pasting will be sent before the actually pasted data. It
makes the raw mode completely transparent (all data received from
console.device are sent to you, but some of them are also interpreted -
such as breaks and the paste).
- CTRL-S and CTRL-Q act as normal XOFF and XON characters. (Used to stop
the output anywhere and to continue afterwards.)
- UNIX mode may be activated. In this case, any line being edited doesn't
stop display output. Some people like it.
- Buffer sizes and other useful constants may be set.
- You can force EOF on the console using the Force command (see below).
You can use this feature if there's someone logged on your system and
you want to disconnect him. This command requires the ss.library
version 5.0 or higher (can be found on the AmiNet).
- You can put the currently edited line to history buffer without sending
it to your program by pressing CTRL-B.
- It's possible to delete not only words delimited by spaces, but also
words consisting only from letters, digits and underlines by CTRL-R.
- All characters except $00 and $9B can be stored to the line. In the raw
mode, no restrictions on character codes apply.
- You can Examine() the console. In this case, the datestamp returned
tells you when has then user typed the last character. (Useful for
WHO-like utilities.)
Multiuser protection
====================
If the multiuser.library is found, full multi-user protection mechanisms
are applied:
- There are no restrictions on screens
- Console and AUX devices normally belong to root and are openable by anyone.
In case first user opens the console, its owner is changed to that user. If it's
released, the owner is set back to root.
- Links are readable by anyone.
- Raw devices act like normal files.
Each device has usual protection bits. They may be altered by the current
owner and are set back to the defaults when the device is closed. If root
modifies the protections, they are set as the defaults.
Access rights are cached on file open, therefore if you pass a filehandle to
anyone, the access rights you had on open are used.
If you are root or you're in the root group, you can do anything the owner
of the file can. Some packets are available only to root.
Default protection bits:
CONSOLE/AUX owner rw, group w, other w
LINK all r
RAWDISK owner rwd (The d bit is set because the copy command
duplicates protection bits and would generate undele-
table files.)
Supported packets
-----------------
This section lists all DOS packets handled by the DEVHandler. Each of these
packets is described, its arguments and access right restrictions are listed.
(1) Standard packets for all devices:
DIE() -> success [ONLY ROOT]
Shut down the handler. Rejected if you are not root or if there still remain
some locks.
CURRENT_VOLUME() -> BPTR volume
Get current (and the only) volume.
LOCATE_OBJECT(BPTR lock,BSTR name,LONG mode) -> BPTR lock
Create a lock.
FREE_LOCK(BPTR lock) -> success
Free a lock.
COPY_DIR(BPTR lock) -> BPTR lock
Duplicate a lock.
SET_PROTECT(zero, BPTR lock, BSTR name, LONG mask) -> success [ONLY OWNER]
Set protection bits. If you are root, the protections are set as a default.
EXAMINE_OBJECT(BPTR lock, BPTR fib) -> success
EXAMINE_NEXT(BPTR lock, BPTR fib) -> success
Standard directory examination mechanism.
DISK_INFO(BPTR infodata) -> success
Get information about current volume.
INFO(BPTR lock,BPTR infodata) -> success
Get information about volume associated with given lock. DEVHandler gives
the same result for all locks.
PARENT(BPTR lock) -> BPTR lock
Get parent of given lock.
SAME_LOCK(BPTR lock1, BPTR lock2) -> result
Compare two locks (see dos/SameLock)
READ(LONG arg1,APTR buffer,LONG size) -> size [READ RIGHTS]
Read data from console/aux/raw device.
WRITE(LONG arg1,APTR buffer,LONG size) -> size [WRITE RIGHTS]
Write data to console/aux/raw device.
FINDUPDATE(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS]
FINDINPUT(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS]
FINDOUTPUT(BPTR lock,BPTR fh,BPTR name) -> success [READ OR WRITE RIGHTS]
Open a file. In case it's a console, the file handle is redirected to the
corresponding internal console handler.
END(LONG arg1) -> success
Close a file.
SEEK(LONG arg1,LONG offset,LONG mode) -> oldpos
Seek a file.
IS_FILESYSTEM() -> TRUE
SET_OWNER(zero, BPTR lock, BSTR name, LONG ugid) -> success [ONLY OWNER]
Set owner of a file.
READ_LINK(BPTR lock,STRPTR name,APTR buffer,LONG size) -> length
Read contents of a soft link.
(2) Standard packets for the console/AUX subhandlers. (If you want to use them,
you must open the console and extract handler port from the file handle.)
WAIT_CHAR(LONG ticks) -> ischar [READ RIGHTS]
Wait for character is available (returns after specified time with FALSE or
with TRUE as soon as some character is available).
DISK_INFO(BPTR infodata) -> success [READ RIGHTS]
Return information about the console:
infodata->id_DiskType = 'CON'<<8 if console, 'RAW'<<8 if con in RAW mode
'CONA' if AUX, 'RAWA' if AUX in RAW mode
infodata->id_VolumeNode = Window (0 if AUX)
infodata->id_InUse = device IORequest
READ(LONG arg1,APTR buffer,LONG size) -> size [READ RIGHTS]
Read data from the console.
WRITE(LONG arg1,APTR buffer,LONG size) -> size [WRITE RIGHTS]
Write data to the console.
SCREEN_MODE(LONG mode) [WRITE RIGHTS]
Switch the console to RAW mode or back (mode=TRUE if RAW, FALSE if not).
CHANGE_SIGNAL(???, APTR task) -> APTR task [WRITE RIGHTS]
Set task to send breaks to.
FINDINPUT,FINDOUTPUT(BPTR lock,BPTR fh,BSTR name) -> success [R or W RIGHTS]
Create a new filehandle for this console. (Used to duplicate a file handle,
for example by NewShell.)
END(LONG arg1) -> success
Close a filehandle.
STACK(LONG arg1,APTR buffer,LONG size) -> size [READ AND WRITE RIGHTS]
Insert something into console buffer. It will be read before all other input.
QUEUE(LONG arg1,APTR buffer,LONG size) -> size [READ AND WRITE RIGHTS]
Insert something into console buffer. It will be read after all other input.
(3) Non-standard packets for the console:
INHIBIT(BOOL flag) -> success [ONLY OWNER]
If flag=TRUE, the console will be blocked until the same packet with flag set
to FALSE. While in inhibited state, the device used by AUX is not touched and
no IORequests are active.
FORCE() -> success [ONLY OWNER]
Force EOF on this console. All read requests are returned with EOF, all write
packets are rejected with error. Break is sent as if CTRL-C and CTRL-D was
pressed.
CHANGE_TERM(LONG termtype) -> success [ONLY OWNER]
Set terminal type to specified one (see DEVHandler.i: DHTERM_#?).
Planned enhancements
====================
- New packet ABORT(LONG arg1) which would try to abort any operation in
progress. (It's sometimes needed to break an already sent console read packet
on program exit.)
- More keyboard commands for the console (e.g., program priority control)
- File name completion in the console
- Console scrollback buffer
- Some packet allowing dynamic creation of devices. (A telnet-daemon could
use this feature.)
- EXAMINE_FH, FH_FROM_LOCK and some other useful packets.
- Setting of default protection bits and default owner in config file.
History
=======
1.0 (17.1.95) - Original release (after almost six months of beta testing)
1.01 (12.2.95) - Example DevHandler.config file included in the archive
(it was mentioned in original doc, but it was missing).
- Two enforcer hits in lock handling functions fixed.
1.02 (14.2.95) - Small bug in DupLock packet (introduced in 1.01) removed.
- The Startup field in Device structure set to 0 (reset back
on exit), because some silly programs (including MUI
VolumeList gadget) incorrectly assumed it to contain
FileSysStartupMsg.
1.03 (15.2.95) - Fixed break handling.
Final words
===========
Send bug reports, flames and suggestions to <mj@k332.feld.cvut.cz>.